home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1999 April: Mac OS SDK / Dev.CD Apr 99 SDK1.toast / Development Kits / Interfaces&Libraries / Universal / Interfaces / CIncludes / QD3DView.h < prev    next >
Encoding:
C/C++ Source or Header  |  1998-08-17  |  14.5 KB  |  451 lines  |  [TEXT/MPS ]
  1. /*
  2.      File:        QD3DView.h
  3.  
  4.      Contains:    View types and routines                                            
  5.  
  6.      Version:    Technology:    Quickdraw 3D 1.5.4
  7.                  Release:    Universal Interfaces 3.2
  8.  
  9.      Copyright:    © 1995-1998 by Apple Computer, Inc., all rights reserved.
  10.  
  11.      Bugs?:        For bug reports, consult the following page on
  12.                  the World Wide Web:
  13.  
  14.                      http://developer.apple.com/bugreporter/
  15.  
  16. */
  17. #ifndef __QD3DVIEW__
  18. #define __QD3DVIEW__
  19.  
  20. #ifndef __QD3D__
  21. #include <QD3D.h>
  22. #endif
  23.  
  24. #ifndef __QD3DSTYLE__
  25. #include <QD3DStyle.h>
  26. #endif
  27. #ifndef __QD3DSET__
  28. #include <QD3DSet.h>
  29. #endif
  30.  
  31.  
  32.  
  33. #if PRAGMA_ONCE
  34. #pragma once
  35. #endif
  36.  
  37. #ifdef __cplusplus
  38. extern "C" {
  39. #endif
  40.  
  41. #if PRAGMA_IMPORT
  42. #pragma import on
  43. #endif
  44.  
  45. #if PRAGMA_STRUCT_ALIGN
  46.     #pragma options align=power
  47. #elif PRAGMA_STRUCT_PACKPUSH
  48.     #pragma pack(push, 2)
  49. #elif PRAGMA_STRUCT_PACK
  50.     #pragma pack(2)
  51. #endif
  52.  
  53. #if PRAGMA_ENUM_ALWAYSINT
  54.     #pragma enumsalwaysint on
  55. #elif PRAGMA_ENUM_OPTIONS
  56.     #pragma option enum=int
  57. #elif PRAGMA_ENUM_PACK
  58.     #if __option(pack_enums)
  59.         #define PRAGMA_ENUM_PACK__QD3DVIEW__
  60.     #endif
  61.     #pragma options(!pack_enums)
  62. #endif
  63.  
  64. /******************************************************************************
  65.  **                                                                             **
  66.  **                        View Type Definitions                                 **
  67.  **                                                                             **
  68.  *****************************************************************************/
  69.  
  70. enum TQ3ViewStatus {
  71.     kQ3ViewStatusDone            = 0,
  72.     kQ3ViewStatusRetraverse        = 1,
  73.     kQ3ViewStatusError            = 2,
  74.     kQ3ViewStatusCancelled        = 3
  75. };
  76. typedef enum TQ3ViewStatus TQ3ViewStatus;
  77.  
  78.  
  79. /******************************************************************************
  80.  **                                                                             **
  81.  **                        Default Attribute Set                                 **
  82.  **                                                                             **
  83.  *****************************************************************************/
  84. #define kQ3ViewDefaultAmbientCoefficient    1.0
  85. #define kQ3ViewDefaultDiffuseColor            0.5, 0.5, 0.5
  86. #define kQ3ViewDefaultSpecularColor            0.5, 0.5, 0.5
  87. #define kQ3ViewDefaultSpecularControl        4.0
  88. #define kQ3ViewDefaultTransparency            1.0, 1.0, 1.0
  89. #define kQ3ViewDefaultHighlightState        kQ3Off
  90. #define kQ3ViewDefaultHighlightColor        1.0, 0.0, 0.0
  91. #define kQ3ViewDefaultSubdivisionMethod        kQ3SubdivisionMethodScreenSpace
  92. #define kQ3ViewDefaultSubdivisionC1            20.0
  93. #define kQ3ViewDefaultSubdivisionC2            20.0
  94.  
  95. /******************************************************************************
  96.  **                                                                             **
  97.  **                            View Routines                                     **
  98.  **                                                                             **
  99.  *****************************************************************************/
  100. EXTERN_API_C( TQ3ViewObject )
  101. Q3View_New                        (void);
  102.  
  103. EXTERN_API_C( TQ3Status )
  104. Q3View_Cancel                    (TQ3ViewObject             view);
  105.  
  106. /******************************************************************************
  107.  **                                                                             **
  108.  **                        View Rendering routines                                 **
  109.  **                                                                             **
  110.  *****************************************************************************/
  111. EXTERN_API_C( TQ3Status )
  112. Q3View_SetRendererByType        (TQ3ViewObject             view,
  113.                                  TQ3ObjectType             theType);
  114.  
  115. EXTERN_API_C( TQ3Status )
  116. Q3View_SetRenderer                (TQ3ViewObject             view,
  117.                                  TQ3RendererObject         renderer);
  118.  
  119. EXTERN_API_C( TQ3Status )
  120. Q3View_GetRenderer                (TQ3ViewObject             view,
  121.                                  TQ3RendererObject *    renderer);
  122.  
  123. EXTERN_API_C( TQ3Status )
  124. Q3View_StartRendering            (TQ3ViewObject             view);
  125.  
  126. EXTERN_API_C( TQ3ViewStatus )
  127. Q3View_EndRendering                (TQ3ViewObject             view);
  128.  
  129. EXTERN_API_C( TQ3Status )
  130. Q3View_Flush                    (TQ3ViewObject             view);
  131.  
  132. EXTERN_API_C( TQ3Status )
  133. Q3View_Sync                        (TQ3ViewObject             view);
  134.  
  135.  
  136. /******************************************************************************
  137.  **                                                                             **
  138.  **                        View/Bounds/Pick routines                             **
  139.  **                                                                             **
  140.  *****************************************************************************/
  141. EXTERN_API_C( TQ3Status )
  142. Q3View_StartBoundingBox            (TQ3ViewObject             view,
  143.                                  TQ3ComputeBounds         computeBounds);
  144.  
  145. EXTERN_API_C( TQ3ViewStatus )
  146. Q3View_EndBoundingBox            (TQ3ViewObject             view,
  147.                                  TQ3BoundingBox *        result);
  148.  
  149. EXTERN_API_C( TQ3Status )
  150. Q3View_StartBoundingSphere        (TQ3ViewObject             view,
  151.                                  TQ3ComputeBounds         computeBounds);
  152.  
  153. EXTERN_API_C( TQ3ViewStatus )
  154. Q3View_EndBoundingSphere        (TQ3ViewObject             view,
  155.                                  TQ3BoundingSphere *    result);
  156.  
  157. EXTERN_API_C( TQ3Status )
  158. Q3View_StartPicking                (TQ3ViewObject             view,
  159.                                  TQ3PickObject             pick);
  160.  
  161. EXTERN_API_C( TQ3ViewStatus )
  162. Q3View_EndPicking                (TQ3ViewObject             view);
  163.  
  164.  
  165. /******************************************************************************
  166.  **                                                                             **
  167.  **                            View/Camera routines                             **
  168.  **                                                                             **
  169.  *****************************************************************************/
  170. EXTERN_API_C( TQ3Status )
  171. Q3View_GetCamera                (TQ3ViewObject             view,
  172.                                  TQ3CameraObject *        camera);
  173.  
  174. EXTERN_API_C( TQ3Status )
  175. Q3View_SetCamera                (TQ3ViewObject             view,
  176.                                  TQ3CameraObject         camera);
  177.  
  178.  
  179. /******************************************************************************
  180.  **                                                                             **
  181.  **                            View/Lights routines                             **
  182.  **                                                                             **
  183.  *****************************************************************************/
  184. EXTERN_API_C( TQ3Status )
  185. Q3View_SetLightGroup            (TQ3ViewObject             view,
  186.                                  TQ3GroupObject         lightGroup);
  187.  
  188. EXTERN_API_C( TQ3Status )
  189. Q3View_GetLightGroup            (TQ3ViewObject             view,
  190.                                  TQ3GroupObject *        lightGroup);
  191.  
  192.  
  193. /******************************************************************************
  194.  **                                                                             **
  195.  **                                Idle Method                                     **
  196.  **                                                                             **
  197.  *****************************************************************************/
  198. /*
  199.  *    The idle methods allow the application to register callback routines 
  200.  *    which will be called by the view during especially long operations.
  201.  *
  202.  *    The idle methods may also be used to interrupt long renderings or
  203.  *    traversals.  Inside    the idler callback the application can check for
  204.  *    Command-Period, Control-C or clicking a "Cancel" button or whatever else
  205.  *    may be used to let the user interrupt rendering.    
  206.  *
  207.  *    It is NOT LEGAL to call QD3D routines inside an idler callback.
  208.  *
  209.  *    Return kQ3Failure to cancel rendering, kQ3Success to continue. Don't
  210.  *    bother posting an error.
  211.  *
  212.  *    Q3View_SetIdleMethod registers a callback that can be called
  213.  *    by the system during rendering.  Unfortunately there is no way yet
  214.  *    to set timer intervals when you want to be called.  Basically, it is
  215.  *    up to the application's idler callback to check clocks to see if you
  216.  *    were called back only a millisecond ago or an hour ago!
  217.  *
  218.  *    Q3View_SetIdleProgressMethod registers a callback that also gives
  219.  *    progress information. This information is supplied by the renderer, and
  220.  *    may or may not be based on real time.
  221.  *
  222.  *    If a renderer doesn't support the progress method, your method will be
  223.  *    called with current == 0 and completed == 0.
  224.  *    
  225.  *    Otherwise, you are GUARANTEED to get called at least 2 or more times:
  226.  *    
  227.  *    ONCE            idleMethod(view, 0, n)        -> Initialize, Show Dialog
  228.  *    zero or more    idleMethod(view, 1..n-1, n) -> Update progress
  229.  *    ONCE            idleMethod(view, n, n)        -> Exit, Hide Dialog
  230.  *    
  231.  *    "current" is guaranteed to be less than or equal to "completed"
  232.  *    "completed" may change values, but current/complete always indicates
  233.  *    the degree of completion.
  234.  *
  235.  *    The calling conventions aid in managing any data associated with a 
  236.  *    progress user interface indicator.
  237.  */
  238. typedef CALLBACK_API_C( TQ3Status , TQ3ViewIdleMethod )(TQ3ViewObject view, const void *idlerData);
  239. typedef CALLBACK_API_C( TQ3Status , TQ3ViewIdleProgressMethod )(TQ3ViewObject view, const void *idlerData, unsigned long current, unsigned long completed);
  240. EXTERN_API_C( TQ3Status )
  241. Q3View_SetIdleMethod            (TQ3ViewObject             view,
  242.                                  TQ3ViewIdleMethod         idleMethod,
  243.                                  const void *            idleData);
  244.  
  245. EXTERN_API_C( TQ3Status )
  246. Q3View_SetIdleProgressMethod    (TQ3ViewObject             view,
  247.                                  TQ3ViewIdleProgressMethod  idleMethod,
  248.                                  const void *            idleData);
  249.  
  250.  
  251. /******************************************************************************
  252.  **                                                                             **
  253.  **                                EndFrame Method                                 **
  254.  **                                                                             **
  255.  *****************************************************************************/
  256. /*
  257.  *    The end frame method is an alternate way of determining when an
  258.  *    asynchronous renderer has completed rendering a frame. It differs from
  259.  *    Q3View_Sync in that notification of the frame completion is the opposite
  260.  *    direction. 
  261.  *    
  262.  *    With Q3View_Sync the application asks a renderer to finish rendering
  263.  *    a frame, and blocks until the frame is complete.
  264.  *    
  265.  *    With the EndFrame method, the renderer tells the application that is has
  266.  *    completed a frame.
  267.  *
  268.  *    If "Q3View_Sync" is called BEFORE this method has been called, this
  269.  *    method will NOT be called ever.
  270.  *    
  271.  *    If "Q3View_Sync" is called AFTER this method has been called, the
  272.  *    call will return immediately (as the frame has already been completed).
  273.  */
  274. typedef CALLBACK_API_C( void , TQ3ViewEndFrameMethod )(TQ3ViewObject view, void *endFrameData);
  275. EXTERN_API_C( TQ3Status )
  276. Q3View_SetEndFrameMethod        (TQ3ViewObject             view,
  277.                                  TQ3ViewEndFrameMethod     endFrame,
  278.                                  void *                    endFrameData);
  279.  
  280.  
  281. /******************************************************************************
  282.  **                                                                             **
  283.  **                            Push/Pop routines                                 **
  284.  **                                                                             **
  285.  *****************************************************************************/
  286. EXTERN_API_C( TQ3Status )
  287. Q3Push_Submit                    (TQ3ViewObject             view);
  288.  
  289. EXTERN_API_C( TQ3Status )
  290. Q3Pop_Submit                    (TQ3ViewObject             view);
  291.  
  292.  
  293. /******************************************************************************
  294.  **                                                                             **
  295.  **        Check if bounding box is visible in the viewing frustum.  Transforms **
  296.  **        the bbox by the current local_to_world transformation matrix and     **
  297.  **        does a clip test to see if it lies in the viewing frustum.             **
  298.  **        This can be used by applications to cull out large chunks of scenes     **
  299.  **        that are not going to be visible.                                     **
  300.  **                                                                             **
  301.  **        The default implementation is to always return kQ3True.  Renderers     **
  302.  **        may override this routine however to do the checking.                 **
  303.  **                                                                             **
  304.  *****************************************************************************/
  305. EXTERN_API_C( TQ3Boolean )
  306. Q3View_IsBoundingBoxVisible        (TQ3ViewObject             view,
  307.                                  const TQ3BoundingBox *    bbox);
  308.  
  309.  
  310. /******************************************************************************
  311.  **                                                                             **
  312.  **                            DrawContext routines                             **
  313.  **                                                                             **
  314.  *****************************************************************************/
  315. EXTERN_API_C( TQ3Status )
  316. Q3View_SetDrawContext            (TQ3ViewObject             view,
  317.                                  TQ3DrawContextObject     drawContext);
  318.  
  319. EXTERN_API_C( TQ3Status )
  320. Q3View_GetDrawContext            (TQ3ViewObject             view,
  321.                                  TQ3DrawContextObject *    drawContext);
  322.  
  323.  
  324. /******************************************************************************
  325.  **                                                                             **
  326.  **                            Graphics State routines                             **
  327.  **                                                                             **
  328.  ** The graphics state routines can only be called while rendering (ie. in     **
  329.  ** between calls to start and end rendering calls).  If they are called     **
  330.  ** outside of a rendering loop, they will return with error.                 **
  331.  **                                                                             **
  332.  *****************************************************************************/
  333. /******************************************************************************
  334.  **                                                                             **
  335.  **                            Transform routines                                 **
  336.  **                                                                             **
  337.  *****************************************************************************/
  338. EXTERN_API_C( TQ3Status )
  339. Q3View_GetLocalToWorldMatrixState (TQ3ViewObject         view,
  340.                                  TQ3Matrix4x4 *            matrix);
  341.  
  342. EXTERN_API_C( TQ3Status )
  343. Q3View_GetWorldToFrustumMatrixState (TQ3ViewObject         view,
  344.                                  TQ3Matrix4x4 *            matrix);
  345.  
  346. EXTERN_API_C( TQ3Status )
  347. Q3View_GetFrustumToWindowMatrixState (TQ3ViewObject     view,
  348.                                  TQ3Matrix4x4 *            matrix);
  349.  
  350.  
  351. /******************************************************************************
  352.  **                                                                             **
  353.  **                            Style state routines                             **
  354.  **                                                                             **
  355.  *****************************************************************************/
  356. EXTERN_API_C( TQ3Status )
  357. Q3View_GetBackfacingStyleState    (TQ3ViewObject             view,
  358.                                  TQ3BackfacingStyle *    backfacingStyle);
  359.  
  360. EXTERN_API_C( TQ3Status )
  361. Q3View_GetInterpolationStyleState (TQ3ViewObject         view,
  362.                                  TQ3InterpolationStyle * interpolationType);
  363.  
  364. EXTERN_API_C( TQ3Status )
  365. Q3View_GetFillStyleState        (TQ3ViewObject             view,
  366.                                  TQ3FillStyle *            fillStyle);
  367.  
  368. EXTERN_API_C( TQ3Status )
  369. Q3View_GetHighlightStyleState    (TQ3ViewObject             view,
  370.                                  TQ3AttributeSet *        highlightStyle);
  371.  
  372. EXTERN_API_C( TQ3Status )
  373. Q3View_GetSubdivisionStyleState    (TQ3ViewObject             view,
  374.                                  TQ3SubdivisionStyleData * subdivisionStyle);
  375.  
  376. EXTERN_API_C( TQ3Status )
  377. Q3View_GetOrientationStyleState    (TQ3ViewObject             view,
  378.                                  TQ3OrientationStyle *    fontFacingDirectionStyle);
  379.  
  380. EXTERN_API_C( TQ3Status )
  381. Q3View_GetReceiveShadowsStyleState (TQ3ViewObject         view,
  382.                                  TQ3Boolean *            receives);
  383.  
  384. EXTERN_API_C( TQ3Status )
  385. Q3View_GetPickIDStyleState        (TQ3ViewObject             view,
  386.                                  unsigned long *        pickIDStyle);
  387.  
  388. EXTERN_API_C( TQ3Status )
  389. Q3View_GetPickPartsStyleState    (TQ3ViewObject             view,
  390.                                  TQ3PickParts *            pickPartsStyle);
  391.  
  392. EXTERN_API_C( TQ3Status )
  393. Q3View_GetAntiAliasStyleState    (TQ3ViewObject             view,
  394.                                  TQ3AntiAliasStyleData * antiAliasData);
  395.  
  396.  
  397. /******************************************************************************
  398.  **                                                                             **
  399.  **                        Attribute state routines                             **
  400.  **                                                                             **
  401.  *****************************************************************************/
  402. EXTERN_API_C( TQ3Status )
  403. Q3View_GetDefaultAttributeSet    (TQ3ViewObject             view,
  404.                                  TQ3AttributeSet *        attributeSet);
  405.  
  406. EXTERN_API_C( TQ3Status )
  407. Q3View_SetDefaultAttributeSet    (TQ3ViewObject             view,
  408.                                  TQ3AttributeSet         attributeSet);
  409.  
  410.  
  411. EXTERN_API_C( TQ3Status )
  412. Q3View_GetAttributeSetState        (TQ3ViewObject             view,
  413.                                  TQ3AttributeSet *        attributeSet);
  414.  
  415. EXTERN_API_C( TQ3Status )
  416. Q3View_GetAttributeState        (TQ3ViewObject             view,
  417.                                  TQ3AttributeType         attributeType,
  418.                                  void *                    data);
  419.  
  420.  
  421.  
  422.  
  423. #if PRAGMA_ENUM_ALWAYSINT
  424.     #pragma enumsalwaysint reset
  425. #elif PRAGMA_ENUM_OPTIONS
  426.     #pragma option enum=reset
  427. #elif defined(PRAGMA_ENUM_PACK__QD3DVIEW__)
  428.     #pragma options(pack_enums)
  429. #endif
  430.  
  431. #if PRAGMA_STRUCT_ALIGN
  432.     #pragma options align=reset
  433. #elif PRAGMA_STRUCT_PACKPUSH
  434.     #pragma pack(pop)
  435. #elif PRAGMA_STRUCT_PACK
  436.     #pragma pack()
  437. #endif
  438.  
  439. #ifdef PRAGMA_IMPORT_OFF
  440. #pragma import off
  441. #elif PRAGMA_IMPORT
  442. #pragma import reset
  443. #endif
  444.  
  445. #ifdef __cplusplus
  446. }
  447. #endif
  448.  
  449. #endif /* __QD3DVIEW__ */
  450.  
  451.